home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / wnx1091.lzh / XES_DEV1.DOC < prev    next >
Text File  |  1991-10-20  |  35KB  |  785 lines
  1.                 XES:  eXtended Environment System
  2.                 =================================
  3.  
  4.  
  5.  
  6.             Official Documentation for XES Programmers
  7.                           October 20,1991
  8.  
  9.                                 by
  10.  
  11.                       Charles H. Medley, Jr.
  12.                          ENiGMA Software
  13.                      659 Kennedy Street, N.E.
  14.                      Washington, D.C.  20011
  15.                           (202) 636-9078
  16.  
  17.  
  18.  
  19.                          Simple Overview
  20.                          +-+-+-+-+-+-+-+
  21.  
  22.      The XES consists of two parts:
  23.  
  24.           o    The TRAP #5 Dispatcher.
  25.  
  26.           o    The User Mode Handler.
  27.  
  28.  
  29.      Every XES function is accessed by passing parameter(s) on the 
  30. stack,  and then doing a TRAP #5.   To allow for full independence 
  31. between copies of Wind-X,  and their utilities, the TRAP #5 simply 
  32. "fixes"  up the parameters and passes them to a subroutine I  call 
  33. the User Mode Handler.
  34.  
  35.      The  purpose  of the User Mode Handler is to  replace  large, 
  36. memory hogging subroutines that would be required for almost every 
  37. WNX application with a simple call.
  38.  
  39.      This  allows the XES to serve as a way to do complicated  AES 
  40. functions,  and  replace large subroutines that would normally  be 
  41. needed  within an application with one call.   A good  example  of 
  42. this  is  XES_REDRAW (43) which can handle window redraws  for  an 
  43. XES-based application,  with just a few lines of code.   I will go 
  44. into detail on how each call works later on in this document.
  45.  
  46.      The method used by the XES is this:
  47.  
  48.           o    Wind-XES does a JSR into the WNX application to
  49.                begin to run it.
  50.  
  51.           o    When  the WNX does a call to the XES (via TRAP  #5) 
  52.                it's execution is stopped, and the system is put in 
  53.                supervisor  mode.   The data and address  registers 
  54.                are saved (A1-A6 and D3-D7 are saved).
  55.  
  56.           o    The  Trap  Handler adjusts the value on  the  stack 
  57.                where  the RTE is to occur (from the TRAP  #5)  and 
  58.                saves  the  RTE address for use by  the  User  Mode 
  59.                Handler,  and  then does an RTE back to the  parent 
  60.                copy of Wind-X's User Mode Handler after setting.
  61.  
  62.           o    The   User  Mode  Handler  performs  the   function 
  63.                requested and JSRs back into the WNX's code at  the 
  64.                location that the TRAP #5 would have RTE'd back to.
  65.                This  means  that  you should NOT try  to  fix  the 
  66.                stack  up,  like  you  do after a  normal  call  to 
  67.                GEMDOS,  because the User Mode Handler has  already 
  68.                dealt with that.   The original A1-A6/D3-D7  values 
  69.                are restored (as of 9/09/90 version  incarnation of
  70.                the XES).
  71.  
  72.           o    This  occurs  over and over until  either  the  WNX 
  73.                process   hits   an  RTS  that   doesn't   have   a 
  74.                corresponding BSR/JSR within it's code, or until it 
  75.                reaches a XES_SUBMIT call.  
  76.  
  77.      One  thing  to note is that all data  and  address  registers 
  78. should  be assumed to be unknown values when a WNX is first  JSRed 
  79. to.   This may change by the time Wind-XES makes it to market, but 
  80. for the most part, this isn't needed.  Also, note that the  SR  is
  81. not properly restored after the TRAP #5 call, so don't count on 
  82. the CCR remaining unchanged after a TRAP #5 as you can with other 
  83. TRAPs.  
  84.  
  85.  
  86.  
  87.  
  88.                      How To Write For the XES
  89.                      +-+-+-+-+-+-+-+-+-+-+-+-
  90.  
  91.      A WNX application has to do two things first:
  92.  
  93.           1)   It  must  call  XES_INIT  with  the  address  of  a 
  94.                parameter block of the form:
  95.  
  96.      Name                Size           Purpose
  97.      ----                ----           -------
  98.      WNX_id              (word)         one word I.D. number, 
  99.                                         assigned by the XES.
  100.      WNX_idname          (16 bytes)     unique 16 byte identifier
  101.                                         set by WNX.
  102.      WNX_apid            (word)         application I.D. of parent 
  103.                                         copy of Wind-X
  104.      WNX_grafhandle      (word)         graphics handle of parent
  105.      WNX_global          (long)         ptr to parent's GLOBAL
  106.                                         array
  107.      WNX_vdiparams       (long)         ptr to parent's VDI
  108.                                         array
  109.      WNX_aesparams       (long)         ptr to parent's AES array
  110.      WNX_messagebuf      (long)         ptr to parent's message
  111.                                         buffer
  112.      WNX_in              (8 words)      WNX_in array
  113.      WNX_out             (8 words)      WNX_out array
  114.      WNX_flags           (word)         event flags (a la the AES
  115.                                         call evnt_multi)
  116.      WNX_link            (long)         address for resuming
  117.                                         execution (used by XES)
  118.      WNX_tcount          (word)         timer count in 20ms 
  119.                                         between events.
  120.      WNX_troutine        (long)         address of TIMER routine
  121.      WNX_mroutine        (long)         address of MESSAGE routine
  122.      WNX_broutine        (long)         address of BUTTON routine
  123.      WNX_kroutine        (long)         address of KEYBOARD
  124.                                         routine
  125.      WNX_rroutine        (long)         address of REDRAW routine
  126.      WNX_termroutine     (long)         address if WNX terminates 
  127.                                         (this    runs   after    a 
  128.                                         WNX_flush call!)
  129.  
  130.                The values for  WNX_id,  WNX_apid,  WNX_grafhandle, 
  131.                WNX_global,      WNX_vdiparams,      WNX_aesparams, 
  132.                WNX_messagebuf,  and  WNX_link are set by  the  XES 
  133.                immediately after this call.
  134.  
  135.           2)   Now,  the WNX must do a XES_RSRCINIT with a pointer 
  136.                to a binary resource that has yet to be fixed up to 
  137.                the proper screen coordinates.  Because the GEM AES 
  138.                is not friendly to programmers who design resources 
  139.                in  color,  various options are allowed with a  one 
  140.                word  flag  which permits you to determine  if  the 
  141.                resource  is  scaled  in any way  relative  to  the 
  142.                screen font size (which is how GEM does it), and if 
  143.                so,  how.   This  first call to  XES_RSRCINIT  will 
  144.                initialize  the resource that will be displayed  in 
  145.                the main Wind-XES window.
  146.  
  147.                Note:  You may also use a resource  that  has  been 
  148.                previously fixed, but the  provision  for  this  is
  149.                not fully implemented as of 8/23/91.   Also,  Laser 
  150.                C's RCP.PRG can generate a  .C  file  that  is,  in 
  151.                essence, a .RSC file that you can "imbed" in your C 
  152.                applications.  It will need a  "fixup",  so  simply 
  153.                pass a pointer to the array it defines,  and  Wind-
  154.                XES will work everything out...
  155.  
  156.           3)   At this point,  the WNX application can do anything 
  157.                it wishes (i.e.  initialize system variables,  find 
  158.                out information about the screen,  etc...) and even 
  159.                call  the XES until it does a  XES_SUBMIT.   It  is 
  160.                good  practice to do the XES_SUBMIT and NOT an  RTS 
  161.                on this part of the code.   The WNX application  is 
  162.                required  to  supply pointers to  subroutines  that 
  163.                should  be executed by Wind-XES  when  events  that 
  164.                it  is looking for occur BEFORE the  XES_SUBMIT  is 
  165.                done.   By  making  the processing the  GEM  events 
  166.                modular  this helps improve  execution  speed,  and 
  167.                makes life easier on WNX programmers,  particularly 
  168.